<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="doctest-soapbox.html" />
<link rel="prev" href="doctest-advanced-api.html" />
<link rel="parent" href="module-doctest.html" />
<link rel="next" href="doctest-soapbox.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>23.2.7 Debugging</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.2.6.6 outputchecker objects"
  href="doctest-OutputChecker.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.2 doctest  "
  href="module-doctest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.2.8 Soapbox"
  href="doctest-soapbox.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="doctest-OutputChecker.html">23.2.6.6 OutputChecker objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-doctest.html">23.2 doctest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-soapbox.html">23.2.8 Soapbox</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0025270000000000000000"></a><a name="doctest-debugging"></a>
<br>
23.2.7 Debugging
</h2>

<p>
Doctest provides several mechanisms for debugging doctest examples:

<p>

<ul>
<li>Several functions convert doctests to executable Python
      programs, which can be run under the Python debugger, <tt class="module"><a href="module-pdb.html">pdb</a></tt>.
</li>
<li>The <tt class="class">DebugRunner</tt> class is a subclass of
      <tt class="class">DocTestRunner</tt> that raises an exception for the first
      failing example, containing information about that example.
      This information can be used to perform post-mortem debugging on
      the example.
</li>
<li>The <tt class="module"><a href="module-unittest.html">unittest</a></tt> cases generated by <tt class="function">DocTestSuite()</tt>
      support the <tt class="method">debug()</tt> method defined by
      <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestCase</tt>.
</li>
<li>You can add a call to <tt class="function"><tt class="module"><a href="module-pdb.html">pdb</a></tt>.set_trace()</tt> in a
      doctest example, and you'll drop into the Python debugger when that
      line is executed.  Then you can inspect current values of variables,
      and so on.  For example, suppose <span class="file">a.py</span> contains just this
      module docstring:

<p>
<div class="verbatim"><pre>
"""
&gt;&gt;&gt; def f(x):
...     g(x*2)
&gt;&gt;&gt; def g(x):
...     print x+3
...     import pdb; pdb.set_trace()
&gt;&gt;&gt; f(3)
9
"""
</pre></div>

<p>
Then an interactive Python session may look like this:

<p>
<div class="verbatim"><pre>
&gt;&gt;&gt; import a, doctest
&gt;&gt;&gt; doctest.testmod(a)
--Return--
&gt; &lt;doctest a[1]&gt;(3)g()-&gt;None
-&gt; import pdb; pdb.set_trace()
(Pdb) list
  1     def g(x):
  2         print x+3
  3  -&gt;     import pdb; pdb.set_trace()
[EOF]
(Pdb) print x
6
(Pdb) step
--Return--
&gt; &lt;doctest a[0]&gt;(2)f()-&gt;None
-&gt; g(x*2)
(Pdb) list
  1     def f(x):
  2  -&gt;     g(x*2)
[EOF]
(Pdb) print x
3
(Pdb) step
--Return--
&gt; &lt;doctest a[2]&gt;(1)?()-&gt;None
-&gt; f(3)
(Pdb) cont
(0, 3)
&gt;&gt;&gt;
</pre></div>

<p>

<span class="versionnote">Changed in version 2.4:
The ability to use <code><tt class="module"><a href="module-pdb.html">pdb</a></tt>.set_trace()</code>
                    usefully inside doctests was added.</span>

</li>
</ul>

<p>
Functions that convert doctests to Python code, and possibly run
the synthesized code under the debugger:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4987' xml:id='l2h-4987' class="function">script_from_examples</tt></b>(</nobr></td>
  <td><var>s</var>)</td></tr></table></dt>
<dd>
  Convert text with examples to a script.

<p>
Argument <var>s</var> is a string containing doctest examples.  The string
  is converted to a Python script, where doctest examples in <var>s</var>
  are converted to regular code, and everything else is converted to
  Python comments.  The generated script is returned as a string.
  For example,

<p>
<div class="verbatim"><pre>
    import doctest
    print doctest.script_from_examples(r"""
        Set x and y to 1 and 2.
        &gt;&gt;&gt; x, y = 1, 2

        Print their sum:
        &gt;&gt;&gt; print x+y
        3
    """)
</pre></div>

<p>
displays:

<p>
<div class="verbatim"><pre>
    # Set x and y to 1 and 2.
    x, y = 1, 2
    #
    # Print their sum:
    print x+y
    # Expected:
    ## 3
</pre></div>

<p>
This function is used internally by other functions (see below), but
  can also be useful when you want to transform an interactive Python
  session into a Python script.

<p>

<span class="versionnote">New in version 2.4.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4988' xml:id='l2h-4988' class="function">testsource</tt></b>(</nobr></td>
  <td><var>module, name</var>)</td></tr></table></dt>
<dd>
   Convert the doctest for an object to a script.

<p>
Argument <var>module</var> is a module object, or dotted name of a module,
   containing the object whose doctests are of interest.  Argument
   <var>name</var> is the name (within the module) of the object with the
   doctests of interest.  The result is a string, containing the
   object's docstring converted to a Python script, as described for
   <tt class="function">script_from_examples()</tt> above.  For example, if module
   <span class="file">a.py</span> contains a top-level function <tt class="function">f()</tt>, then

<p>
<div class="verbatim"><pre>
import a, doctest
print doctest.testsource(a, "a.f")
</pre></div>

<p>
prints a script version of function <tt class="function">f()</tt>'s docstring,
  with doctests converted to code, and the rest placed in comments.

<p>

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4989' xml:id='l2h-4989' class="function">debug</tt></b>(</nobr></td>
  <td><var>module, name</var><big>[</big><var>, pm</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Debug the doctests for an object.

<p>
The <var>module</var> and <var>name</var> arguments are the same as for function
  <tt class="function">testsource()</tt> above.  The synthesized Python script for the
  named object's docstring is written to a temporary file, and then that
  file is run under the control of the Python debugger, <tt class="module"><a href="module-pdb.html">pdb</a></tt>.

<p>
A shallow copy of <code><var>module</var>.__dict__</code> is used for both local
  and global execution context.

<p>
Optional argument <var>pm</var> controls whether post-mortem debugging is
  used.  If <var>pm</var> has a true value, the script file is run directly, and
  the debugger gets involved only if the script terminates via raising an
  unhandled exception.  If it does, then post-mortem debugging is invoked,
  via <code><tt class="module"><a href="module-pdb.html">pdb</a></tt>.post_mortem()</code>, passing the traceback object
  from the unhandled exception.  If <var>pm</var> is not specified, or is false,
  the script is run under the debugger from the start, via passing an
  appropriate <tt class="function">execfile()</tt> call to <code><tt class="module"><a href="module-pdb.html">pdb</a></tt>.run()</code>.

<p>

<span class="versionnote">New in version 2.3.</span>

<p>

<span class="versionnote">Changed in version 2.4:
The <var>pm</var> argument was added.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4990' xml:id='l2h-4990' class="function">debug_src</tt></b>(</nobr></td>
  <td><var>src</var><big>[</big><var>, pm</var><big>]</big><var></var><big>[</big><var>, globs</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Debug the doctests in a string.

<p>
This is like function <tt class="function">debug()</tt> above, except that
  a string containing doctest examples is specified directly, via
  the <var>src</var> argument.

<p>
Optional argument <var>pm</var> has the same meaning as in function
  <tt class="function">debug()</tt> above.

<p>
Optional argument <var>globs</var> gives a dictionary to use as both
  local and global execution context.  If not specified, or <code>None</code>,
  an empty dictionary is used.  If specified, a shallow copy of the
  dictionary is used.

<p>

<span class="versionnote">New in version 2.4.</span>

</dl>

<p>
The <tt class="class">DebugRunner</tt> class, and the special exceptions it may raise,
are of most interest to testing framework authors, and will only be
sketched here.  See the source code, and especially <tt class="class">DebugRunner</tt>'s
docstring (which is a doctest!) for more details:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-4991' xml:id='l2h-4991' class="class">DebugRunner</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>checker</var><big>]</big><var></var><big>[</big><var>,
                                 verbose</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>

<p>
A subclass of <tt class="class">DocTestRunner</tt> that raises an exception as
    soon as a failure is encountered.  If an unexpected exception
    occurs, an <tt class="exception">UnexpectedException</tt> exception is raised,
    containing the test, the example, and the original exception.  If
    the output doesn't match, then a <tt class="exception">DocTestFailure</tt>
    exception is raised, containing the test, the example, and the
    actual output.

<p>
For information about the constructor parameters and methods, see
    the documentation for <tt class="class">DocTestRunner</tt> in
    section&nbsp;<a href="doctest-advanced-api.html#doctest-advanced-api">23.2.6</a>.
</dl>

<p>
There are two exceptions that may be raised by <tt class="class">DebugRunner</tt>
instances:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4992' xml:id='l2h-4992' class="exception">DocTestFailure</tt></b>(</nobr></td>
  <td><var>test, example, got</var>)</td></tr></table></dt>
<dd>
    An exception thrown by <tt class="class">DocTestRunner</tt> to signal that a
    doctest example's actual output did not match its expected output.
    The constructor arguments are used to initialize the member
    variables of the same names.
</dl>
<tt class="exception">DocTestFailure</tt> defines the following member variables:
<dl><dt><b><tt id='l2h-4993' xml:id='l2h-4993' class="member">test</tt></b></dt>
<dd>
    The <tt class="class">DocTest</tt> object that was being run when the example failed.
</dl>
<dl><dt><b><tt id='l2h-4994' xml:id='l2h-4994' class="member">example</tt></b></dt>
<dd>
    The <tt class="class">Example</tt> that failed.
</dl>
<dl><dt><b><tt id='l2h-4995' xml:id='l2h-4995' class="member">got</tt></b></dt>
<dd>
    The example's actual output.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4996' xml:id='l2h-4996' class="exception">UnexpectedException</tt></b>(</nobr></td>
  <td><var>test, example, exc_info</var>)</td></tr></table></dt>
<dd>
    An exception thrown by <tt class="class">DocTestRunner</tt> to signal that a
    doctest example raised an unexpected exception.  The constructor
    arguments are used to initialize the member variables of the same
    names.
</dl>
<tt class="exception">UnexpectedException</tt> defines the following member variables:
<dl><dt><b><tt id='l2h-4997' xml:id='l2h-4997' class="member">test</tt></b></dt>
<dd>
    The <tt class="class">DocTest</tt> object that was being run when the example failed.
</dl>
<dl><dt><b><tt id='l2h-4998' xml:id='l2h-4998' class="member">example</tt></b></dt>
<dd>
    The <tt class="class">Example</tt> that failed.
</dl>
<dl><dt><b><tt id='l2h-4999' xml:id='l2h-4999' class="member">exc_info</tt></b></dt>
<dd>
    A tuple containing information about the unexpected exception, as
    returned by <tt class="function">sys.exc_info()</tt>.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.2.6.6 outputchecker objects"
  href="doctest-OutputChecker.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.2 doctest  "
  href="module-doctest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.2.8 Soapbox"
  href="doctest-soapbox.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="doctest-OutputChecker.html">23.2.6.6 OutputChecker objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-doctest.html">23.2 doctest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-soapbox.html">23.2.8 Soapbox</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
